home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / tclX6.4c / dist / experimental / debugger / README.DEBUG < prev   
Encoding:
Text File  |  1992-03-12  |  6.4 KB  |  189 lines
  1.  
  2.  
  3.  
  4.                 A SOURCE LEVEL DEBUGGER FOR TCL
  5.  
  6.                       by
  7.  
  8.                 Karl Lehenbauer
  9.                    (karl@neosoft.com)
  10.  
  11.               Thu Jan 02 13:20:53 CST 1992
  12.  
  13.  
  14.  
  15. WHAT IS THIS?
  16. =============
  17.  
  18. This is the first cut of an experimental debugger that allows Extended
  19. Tcl programmers to set breakpoints, single step through procedures with 
  20. "step in" and "step over", and access and manipulate the environment of 
  21. the procedure being debugged.
  22.  
  23. Something interesting about the debugger is that most of it is written
  24. in Tcl; enough C code was written to connect Tcl's capability to call a
  25. C routine every time a Tcl statement is executed back into Tcl to the
  26. point where it could call and execute a Tcl procedure, and provide
  27. control over its behavior.
  28.  
  29. Thus, Tcl programmers can extend and modify the debugger without dropping
  30. into C.  The current "trace_step" routine, while providing some powerful
  31. capabilities, is nonetheless a dim shadow of what is possible.  For those
  32. wishing to enhance the debugger, some suggested capabilities are described
  33. below.
  34.  
  35. COMMAND SUMMARY
  36. ===============
  37.  
  38. After getting Tcl built with the debugging code (see HOW TO INSTALL IT,
  39. below), starting tcl and doing a "source debug.tcl", the following
  40. commands are available:
  41.  
  42. traceproc procName [args...]
  43.  
  44.     Traces procedure procName, the debugger will print the name
  45.     of the routine and it's prompt, currently 
  46.  
  47.     While tracing, before a statement is executed, the prompt "ncsa!?"
  48.     is output.
  49.  
  50.     Enter "n" and RETURN, or just RETURN, to step over the routine, i.e.
  51.     execute it but not trace it.
  52.  
  53.     Enter "s" (and RETURN, always), to step *into* the routine, to
  54.     start stepping the statements that comprise the routine.
  55.  
  56.     Enter "c" to execute the rest of the routine being stepped without
  57.     stopping.
  58.  
  59.     Enter "a" to show the command about to be executed, only with
  60.     any subordinate variable substitutions and square-bracketed
  61.     statements expanded.  This is neat.  Note that by how Tcl works
  62.     not every variable or expression may have been expanded.
  63.  
  64.     Enter "!" to push to a tcl command loop which will be at the
  65.     same execution level as the procedure being traced, so you can
  66.     do an "info vars", look at variables, change them, and so forth.
  67.     (You can also use "info globals" to poke around the global vars.)
  68.     Type control-D to return to the debugger "ncsa!?" prompt.
  69.  
  70.     If you include text past the "!", it will execute the text as
  71.     a statement then immediately return, so you can do things like:
  72.  
  73.     ncsa!? !info vars
  74.  
  75.     Entering "?" gets you a few lines of help.
  76.  
  77.  
  78. bp [procName...]
  79.  
  80.     Set a breakpoint on entry to one or more named procedures.
  81.     If no names are specified, currently breakpoint procedures
  82.     are printed (sort of, they're printed, but with a spurious
  83.     "_bp" tagged onto the end of each one.)
  84.  
  85. bc [procName...]
  86.  
  87.     Clear a breakpoint on one or more named procedures, or all
  88.     all breakpoints if none is specified.
  89.  
  90. tp procName [args...]
  91.  
  92.     A shorthand for "traceproc".
  93.  
  94.  
  95. HOW TO INSTALL IT
  96. =================
  97.  
  98. o Copy  ndebug.c to the src directory.
  99.  
  100. o Add ndebug.o to the OBJS macro in src/Makefile
  101.  
  102. o Added a call to `Tcl_InitnDebug (interp);' in Tcl_CreateExtendedInterp in
  103.   the file src/createExtd.c.
  104.  
  105. o Copy ndebug.tcl to the tclsrc directory.
  106.  
  107. o Added ndebug.tcl to the TCL_LIBFILES macro in tclsrc/Makefile
  108.  
  109. o Rebuild and optionally reinstall Extended Tcl.
  110.  
  111. HOW IT WORKS
  112. ============
  113.  
  114. The "traceproc" command takes a procedure name and optional args, and
  115. executes it with tracing enabled.
  116.  
  117.     traceproc procname [args...]
  118.  
  119. The "trace_step" procedure is executed every time a statement in the
  120. procedure being traced is executed, subject to more control described
  121. below.
  122.  
  123. "trace_step" receives three arguments, the depth of the interpreter,
  124. the command that's being executed, and the command that's being
  125. executed with subordinate square bracketed statements expanded,
  126. variables substituted, and so forth.
  127.  
  128. Of course trace_step itself is not traced -- that's the magic that makes
  129. it all work.
  130.  
  131. Note that the C trace trace routine is still called, it just returns
  132. immediately -- a trace routine cannot delete itself.  The C code in
  133. baseline Tcl that handles execution tracing just can't deal with it at
  134. this time.
  135.  
  136. tracecon depth [level]
  137. tracecon depthfloor [level]
  138.  
  139. The tracing depth in interpreter levels is set and fetched with the
  140. variants of "tracecon depth".  The depth floor sets the lowest level
  141. we can trace.  Examine debug.tcl to see how the depth and depth floor
  142. can be manipulated to achieve "step in" and "step over".
  143.  
  144. These will probably be replaced by standard tcl variables -- that would
  145. make a lot of sense.  It would, however, increase the execution overhead
  146. of the trace routine, even when there was nothing to be traced.  Perhaps
  147. the variable tracing from C capability could be used to monitor changes
  148. in the values of the variables and, when they're changed, convert them
  149. to the static integers that the C trace procedure, TraceRoutine, would
  150. examine very quickly.
  151.  
  152.  
  153. WHAT TO EXPECT IN THE FUTURE
  154. ============================
  155.  
  156. This package represents a first cut and, since it's so new and since it's
  157. really just scratching the surface of a fertile area of interest, I expect
  158. that it will evolve greatly as people use it and figure out improvements
  159. for it.
  160.  
  161. I have no commitment to any long-term support of this version.
  162.  
  163. Markd@Grizzly.com points out that, since a debugger stands alone from the
  164. code you're developing, evolution of the debugger doesn't have nearly
  165. as large of an impact on developers as, say, evolution of the language itself.
  166.  
  167.  
  168. SOME POSSIBLE ENHANCEMENTS
  169. ==========================
  170.  
  171. It would be nice to have commands to dump local and global variables, all
  172. or by name, and prettily, as parray.tcl does.
  173.  
  174. Tracing variables by printing their contents as they change would be nice.
  175. (I am not talking about Tcl's variable trace capability.)
  176.  
  177. Locating the position in a source file or in the procedure body and cursor
  178. addressing to provide a more screen-oriented debugger.  (Tcl error management
  179. knows how to figure it out, so see how it does it.)
  180.  
  181. trace_step calling a managed list of subordinate routines to implement
  182. these sorts of things.
  183.  
  184. It would be nice to be able to abort the execution of the trace.  This is hard
  185. because there is currently no mechanism for a C trace to control the 
  186. interpreter, only for it to passively see what's going to happen next.
  187.  
  188. A trace where it executes a number of statements, not just one.
  189.